lab components / Data Visualization

Polar Gauge (DCI Score Gauge)

Visually communicates progress toward a goal or target as a percentage within a circular format. The circle represents 100%.

Examples Basic Usage Animation Changes Usage Properties Guidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { DCIGauge } from "@siteimprove/fancylab";

#Examples

Primarily used for DCI scores, but can be adapted for other Siteimprove metrics with a target of 100. Ideal for tracking key performance indicators (KPIs) and completion rates. Ensure the goal is clear to the user.

The component consists of:

Product Title: Clearly indicates the metric being tracked (e.g., "DCI Score").
Score: Displays the current score in a x/100 format (e.g., "25.9/100").
Progress Indicator: Visually represents the score as a filled portion of the circle.
Progress Change: Shows the change in score over a specified period (e.g., "+50.0") with a tooltip explaining the change (e.g., "Change to your score over the last 30 days").
Custom Site Target Button: (Icon-only) Allows the user to view the target score.
Industry Benchmark Button: (Icon-only) Provides a comparison to industry averages.

#Basic Usage

Product Title

0.0 /100

undefined: 75.0undefined: 90.0

CodeHTML output

return (
	<DCIGauge
		title="Product Title"
		scoreValue={25}
		benchmark={75}
		benchmarkSupportLink={
			"https://support.siteimprove.com/hc/en-gb/articles/115001853672-What-is-the-industry-benchmark"
		}
		delta={{ value: 50, tooltipText: "Tooltip text", ariaLabel: "Change last 30 days:" }}
		target={90}
		currentIndustryName={"Industry Name"}
	/>
);

#Animation Changes Usage

If you are unsatisfied with the default delay and duration of the animations, you can set them yourself to make the animation go faster or slower.

Product Title

0.0 /100

undefined: 75.0undefined: 90.0

CodeHTML output

return (
	<DCIGauge
		title="Product Title"
		scoreValue={25}
		benchmark={75}
		benchmarkSupportLink={
			"https://support.siteimprove.com/hc/en-gb/articles/115001853672-What-is-the-industry-benchmark"
		}
		delta={{ value: 50, tooltipText: "Tooltip text", ariaLabel: "Change last 30 days:" }}
		target={90}
		currentIndustryName={"Industry Name"}
		animationDelay={0}
		animationDuration={600}
	/>
);

#Properties

Product Title

0.0 /100

undefined: 75.0undefined: 90.0

CodePropsHTML output

Property	Description	Defined
titleRequired	`string`	YesNo
scoreValueRequired	`number`	YesNo
benchmarkOptional	`number`Value for the industry benchmark score	YesNo
targetOptional	`number`Value for the user set target score	YesNo
currentIndustryNameOptional	`string`	YesNo
benchmarkSupportLinkOptional	`string`	YesNo
aria-labelOptional	`string`Label for the gauge	YesNo
deltaOptional	`object`Values for the circular progress component animation	YesNo
animationDelayOptional	`number`Value that overrides the delay between animations	YesNo
animationDurationOptional	`number`Value that overrides the duration of animations	YesNo

A visual representation of progress is more impactful than a raw number.
The metric being tracked should have a defined target of 100.

#Placement

DCIGauge is typically used in the following places:

Dashboard overview: Provide a quick snapshot of progress.
Detailed reports: Supplement numerical data with a visual indicator.
Widgets: Offer a compact progress summary.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your DCIGauge to existing components for visual consistency.
Purposeful Animation:
- Meaningful Motion: Animation should enhance, not distract from, the user experience. Each motion should have a clear purpose tied to improving comprehension or usability. For example, staggered animations can guide the user’s eye to data points in a specific order, highlighting key information.
- User-Centered Timing: Animation speed should be deliberate and based on user needs, not arbitrary aesthetic choices. “Faster” or “slower” is subjective; instead, consider:
  - Does this speed help users grasp the information effectively?
  - Does it feel natural and intuitive within the flow of the interface?
  - Does it complement the gauge’s function and the overall user experience?

#Do not use when

The data is highly volatile: A gauge isn't suitable for rapidly changing values. Use Chart or other data visualisation.
Precise numerical values are critical: A gauge is an approximation; use a numerical display if exact figures are necessary. Use Highlight component instead.
The metric does not have a target of 100: A gauge requires a defined goal to measure against.